// Copyright (C) 2009 Jesse Jones
//
// Permission is hereby granted, free of charge, to any person obtaining
// a copy of this software and associated documentation files (the
// "Software"), to deal in the Software without restriction, including
// without limitation the rights to use, copy, modify, merge, publish,
// distribute, sublicense, and/or sell copies of the Software, and to
// permit persons to whom the Software is furnished to do so, subject to
// the following conditions:
// 
// The above copyright notice and this permission notice shall be
// included in all copies or substantial portions of the Software.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

using System;
using System.Collections.Generic;

namespace MmmDoc.Database
{
	/// <summary>The documentation associated with a program element (e.g. a type or method).</summary>
	/// <remarks>Note that all of these properties may be null.</remarks>
	internal sealed class Definition
	{
		public Definition()
		{
			Examples = new List<Markup>();
			Exceptions = new List<LabeledMarkup<CodeReference>>();		// note that don't use Dictionary<CodeReference, Markup> because we want to preserve the user's ordering
			Params = new List<LabeledMarkup<string>>();
			Permissions = new List<LabeledMarkup<string>>();
			SeeAlso = new List<CodeReference>();
			TypeParams = new List<LabeledMarkup<string>>();
		}
		
		/// <summary>One or more examples associated with the program element.</summary>
		public List<Markup> Examples {get; set;}
		
		/// <summary>Exceptions which may be thrown by the program element.</summary>
		/// <returns>The key is the name of the exception. This name will be fully qualified.</returns>
		public List<LabeledMarkup<CodeReference>> Exceptions {get; set;}
		
		/// <summary>Documentation for method arguments.</summary>
		/// <remarks>The string is the argument name, e.g. "index".</remarks>
		public List<LabeledMarkup<string>> Params {get; set;}
		
		/// <summary>Security permissions associated with the program element.</summary>
		/// <returns>The key is the name of the security type. The names will be fully qualified.</returns>
		public List<LabeledMarkup<string>> Permissions {get; set;}
		
		/// <summary>More detailed information about the program element.</summary>
		/// <returns>May be null.</returns>
		public Markup Remarks {get; set;}
		
		/// <summary>Documentation for the return value of a method.</summary>
		/// <returns>May be null.</returns>
		public Markup Returns {get; set;}
		
		/// <summary>Pointers to related elements.</summary>
		/// <returns>The values are the element names (e.g. a type or method). The names will be fully qualified.</returns>
		public List<CodeReference> SeeAlso {get; set;}
		
		/// <summary>Overview of the program element.</summary>
		/// <returns>May be null.</returns>
		public Markup Summary {get; set;}
		
		/// <summary>Documentation for generic type parameters.</summary>
		/// <remarks>The string is the type name, e.g. "T".</remarks>
		public List<LabeledMarkup<string>> TypeParams {get; set;}
		
		/// <summary>Documentation for the implicit value argument in property setters.</summary>
		/// <returns>May be null.</returns>
		public Markup Value {get; set;}
		
		/// <summary>True if the program element should not appear in the documentation.</summary>
		public bool Excluded {get; set;}
		
		/// <summary>True if an empty type should not appear in the documentation.</summary>
		public bool ExcludeIfEmpty {get; set;}
	}
}
